Summary

• Adds docs/agents/formats/claude-code/ — a practitioner-grade reference for Claude Code's on-disk JSONL session format. Twelve focused docs cover the envelope, entry types, the message object, tool-call lifecycle, token accounting, session chains and compaction, peripheral files, the empirical rules for writing Claude-compatible JSONL, known issues, a linear walkthrough, and a version-keyed format changelog.
• Reference revision 2026-04-23; tracks Claude Code 2.1.x (first-hand samples 2.1.37 through 2.1.112). The top-level README carries a revision stamp that future editors are instructed to bump.
• Wires the reference into existing signposts so it's actually findable:
  • Root README.md and CLAUDE.md link into it.
  • crates/toolpath-claude/README.md calls it the authoritative spec.
  • writing-compatible-jsonl.md and crates/toolpath-cli/src/cmd_incept.rs cross-reference each other; cmd_incept.rs is documented as the reference writer for the "write-compatible JSONL" rules.
• Updates docs/agents/formats/README.md (the format-directory index) to also point at the existing sibling codex.md, gemini.md, opencode.md single-file references that landed on main alongside this work.
• Includes a trailing fmt commit touching four unrelated files (toolpath-claude/src/derive.rs, toolpath-cli/src/bin/gen_synthetic_path.rs, toolpath-convo/src/derive.rs, toolpath-desktop/src/tray.rs) — pure cargo fmt --all output, no logic changes. Kept as a separate commit for auditability.

What's not in this PR (by design)

• No fixtures / conformance suite. The walkthrough's JSONL is synthesized and explicitly marked as illustrative. A machine-testable corpus would be the next commit to push this from reference-quality toward specification-quality; deliberately scoped out here.
• No site rendering. The docs live in-repo only; site/ isn't wired up to publish them.

Both gaps are called out in commit history and in format-changelog.md's maintenance process.

Test plan

• cargo check -p toolpath-cli passes (cmd_incept.rs gained a module-level doc comment pointing at writing-compatible-jsonl.md).
• All internal markdown cross-links resolve — verified with a scripted pass over each .md under docs/agents/formats/claude-code/.
• Parser-surface table in jsonl-envelope.md matches ConversationEntry in crates/toolpath-claude/src/types.rs field-for-field.
• Revision stamp at top of docs/agents/formats/claude-code/README.md agrees with the date in format-changelog.md.
• Spot-read the walkthrough.md — each entry-type class appears at least once (permission-mode, direct user, assistant with tool_use, tool_result carrier, text-only assistant, turn_duration, compact_boundary, synthetic summary, follow-up, rotation and sidechain previews).